Welcome

Welcome to Network Stumbler

This help file contains information that may help you to use NetStumbler more effectively.

NOTE: Some help topics are incomplete. Please do not complain about this.

  • Release notes and Frequently Asked Questions
  • Suggested Usage and Configuration Examples
  • User Interface
  • Scripting Guide
  • Glossary
  • License Agreement


NetStumbler readme

NetStumbler v0.4.0 Release Notes

Marius Milner <mariusm@pacbell.net>

Thank you for your interest in NetStumbler. It is provided to you as a convenience, at no cost and without warranty. If you don't like it, or if you feel that it doesn't quite do what you want, you are free to delete it from your system. By installing or using it, you agree to be bound by the terms of the License Agreement.

NetStumbler is "beggarware". This means that you do not have to pay for a license to use it. However if you use it and like it, please consider making a donation at http://www.stumbler.net/donate to support future development, web hosting and other costs that I incur as a result of making this software available to you. Please bear in mind that I do this as a hobby in my spare time, not as a full time job.

Commercial and Government users are strongly encouraged to donate. The suggested donation is US$50 per copy. You may donate by visiting the web site http://www.stumbler.net/donate. You can pay in a variety of ways and may send a Purchase Order if needed.

What is NetStumbler?

NetStumbler is a tool for Windows that allows you to detect Wireless Local Area Networks (WLANs) using 802.11b, 802.11a and 802.11g. It has many uses:

  • Verify that your network is set up the way you intended.
  • Find locations with poor coverage in your WLAN.
  • Detect other networks that might be causing interference with your network.
  • Detect unauthorized "rogue" access points in your workplace.
  • Help aim directional antennas for long-haul WLAN links.
  • Use it recreationally for WarDriving.

Requirements

General Requirements

The requirements for NetStumbler are somewhat complex and depend on hardware, firmware versions, driver versions and operating system. The best way to see if it works on your system is to try it.

Some configurations have been extensively tested and are known to work. These are detailed at http://www.stumbler.net/compat. If your configuration works but is not listed, or is listed but does not work, please follow the instructions on the web site.

The following are rules of thumb that you can follow in case you cannot reach the web site for some reason.

  • This version of NetStumbler requires Windows 2000, Windows XP, or better.
  • The Proxim models 8410-WD and 8420-WD are known to work. The 8410-WD has also been sold as the Dell TrueMobile 1150, Compaq WL110, Avaya Wireless 802.11b PC Card, and others.
  • Most cards based on the Intersil Prism/Prism2 chip set also work.
  • Most 802.11b, 802.11a and 802.11g wireless LAN adapters should work on Windows XP. Some may work on Windows 2000 too. Many of them report inaccurate Signal strength, and if using the "NDIS 5.1" card access method then Noise level will not be reported. This includes cards based on Atheros, Atmel, Broadcom, Cisco and Centrino chip sets.
  • I cannot help you figure out what chip set is in any given card.

Firmware Requirements

If you have an old WaveLAN/IEEE card then please note that the WaveLAN firmware (version 4.X and below) does not work with NetStumbler. If your card has this version, you are advised to upgrade to the latest version available from Proxim's web site. This will also ensure compatibility with the 802.11b standard.

Other Requirements and Compatibility Issues

  • Your card must be configured in such a way that it can be seen by the management software that came with the card.
  • The Microsoft-provided Orinoco drivers that come with Windows 2000 do not work with NetStumbler. Please visit Windows Update or www.proxim.com and upgrade to the latest drivers.
  • When NetStumbler is in "auto reconfigure" mode (the default), it will occasionally disconnect you from your network. This enables it to perform its scans accurately, and is not a bug.
  • If you have the WLAN card configured to connect to a specific SSID, NetStumbler may not report any accees points other than those that have that SSID. Configure your card with a blank SSID or, if a blank one is not permitted, "ANY" (without quotes).

Legal note

I am not a lawyer. However as a user of this software, you need to be aware of the following.

In most places, it is illegal to use a network without permission from the owner. The definition of "use" is not entirely clear, but it definitely includes using someone else's internet connection or gathering information about what is on the network. It may include getting an IP address via DHCP. It may even include associating with the network.

The IP address reporting functionality in NetStumbler is for you to check the settings of your own network, and for corporate users to identify rogue access points operating within their organization. If you are doing neither of these things, it is suggested that you disable TCP/IP on your wireless adapter. This will help you to avoid possible legal trouble.

Marius Milner, netstumbler.com and stumbler.net accepts no liability for damages caused by use of this software. For further information please consult the License Agreement that can be found both in the installer and in the online help.

Mini-FAQ

Q1. NetStumbler reports "No wireless card found". Why?
A1. Please check the compatibility lists above. Perhaps your adapter is not supported.
Q2. Why doesn't NetStumbler see the access point right next to my machine?
A2A. The access point is configured not to respond to broadcast probes. Most manufacturers call this "disable broadcast SSID" or "closed". NetStumbler cannot see these networks unless you know the SSID and have your machine configured to connect to it.
A2B. Your wireless card is configured to connect to a specific SSID. Try setting it to connect to a blank SSID or to "ANY" (without quotes).
Q3. What 802.11 frames does NetStumbler send?
A3A. It sends out a probe request about once a second, and reports the responses. This is known as Active Scanning.
A3B. (ORiNOCO only and with "Query APs for names" enabled) When it is connected to a BSS network, it will attempt to get the name of the access point. When it is connected to an IBSS network, it will try to get the names of all locally visible peers. This is done via Proxim's proprietary WMP protocol.
A3C. (Only when connected to a Cisco access point and with "Query APs for names" enabled and with a valid IP address ) It will attempt to use Cisco's IAPP protocol to get the name and IP address of the access point.
A3D. If you leave TCP/IP enabled, your adapter may attempt to get a DHCP lease or send other traffic. NetStumbler will record the fact that you were issued an IP address.
Q4. Does NetStumbler listen for beacons, or put my card into promiscuous or RFMON mode?
A4. This is called Passive Scanning and is not in this version.
Q5. I'm seeing access points appear briefly and then disappear for a long time. What's happening?
A5A. Some wireless networks can be configured not to respond to probes every time they hear a request.
A5B. If you see lots of networks that appear briefly and then disappear forever, you may have found a FakeAP installation.
Q6. Why does NetStumbler disconnect me from the network?
A6. If you have "Options->Reconfigure card automatically" checked, it will configure your card with a profile that uses a null SSID and BSS mode (It will not change your WEP settings). Also, when it sees another network that has a better signal than the one you're connected to, it may disconnect the current connection so that it can get the AP name on the other network.
Q7. Does NetStumbler detect ROR and COR installations?
A7. Not usually. They are not always fully compliant with 802.11b and therefore may not be visible to NetStumbler.
Q8. Should I allow Windows XP to manage my wireless settings?
A8. Probably not. When you are not connected to a network, XP will cycle through your favorite network names attempting to connect to them. While this is happening, NetStumbler may not see all available networks. It is recommended that you stop the "Wireless Zero Configuration" service while NetStumbler is running. You can do this by switching on "Auto Reconfigure", from Control Panel, or by running the command "net stop wzcsvc".
Q9. When will you support wireless card X? When will you add new feature Y that I want?
A9. I work on this in my spare time. I can make no commitment to dates for new features or bug fixes. If you would like to help me support a particular piece of hardware, please consider sending me a sample rather than complaining that it isn't supported.
Q10. What does "Auto Reconfigure" actually do?
A10A. When using the ORiNOCO driver, it stops the Wireless Zero Configuration service and makes sure that the card is always set to a blank SSID and BSS mode.
A10B. When using the Prism driver, it stops the Wireless Zero Configuration service and checks for a blank or "ANY" SSID. If necessary, it makes changes to the card's registry settings and prompts you to reinsert the card.
A10C. On all other drivers, it stops the Wireless Zero Configuration service and then does nothing. Usually this is a good thing, but you should experiment with it.

Release History

Version 0.4.0 (April 21, 2004)

  • Fixed bug (introduced in 0.3.30) that caused "Reconfigure" to put ORiNOCO cards into a state where they would report no access points.
  • Support for Atheros, Atmel, Intersil Prism based wireless cards. Improved support for Cisco cards.
  • Allow use of Serial Earthmate GPS. (USB Earthmate should already work using NMEA and serial driver)
  • If you scroll all the way to the right of the graph view, it will auto-scroll new data.
  • Fixed bug (introduced in 0.3.30) in graph view: corrupted display when scrolling.
  • Fixed bug in graph view: improper scroll bar tracking with large data sets.
  • If "Reconfigure" is on, the Windows XP Wireless Zero Configuration service will be stopped when you start scanning. It is restarted when the application exits.
  • If you connect to a network that supports DHCP, the IP subnet is reported.
  • If the access point is discovered in the ARP table, its IP address is reported.
  • While you are scanning, the system will be prevented from going into standby unless power is critically low.
  • Large files load several times faster than before (though the really large ones still don't load fast enough).
  • A whole lot of new Scripting features.

Version 0.3.30 (August 18, 2002):

  • Allow configuration of baud rate and other settings for GPS.
  • Added "Default SSID" filter to tree view.
  • Close connection to NIC when scanning is not happening.
  • Moved much of the configuration to a dialog box.
  • Support for user-provided scripts to be invoked when various events occur.
  • Many errors are reported in a more meaningful way.
  • Workaround for problem with driver version 7.62.
  • GPS now supports Garmin proprietary protocols.
  • (NetStumbler) MIDI output of signal strength(s).
  • (NetStumbler) Proper installation package (thank you Nullsoft)
  • (NetStumbler) Use NDIS 5.1 native 802.11 features for scanning on Cisco and some Prism cards on Windows XP.
  • (NetStumbler) Support for 802.11a on Windows XP.
  • (NetStumbler) Support for USB devices on 98/Me.

Version 0.3.23 (February 14, 2002):

  • Count of filtered and all APs in bottom right corner.
  • Handle "ASTRAL" on serial port so that Tripmate can be used.
  • Autosave feature added.
  • Popup menu allows deletion of APs from list.
  • Complete rewrite of NIC access code in preparation for multiple chipset support.
  • (MiniStumbler) First public release. No tree or graph view.

Version 0.3.22 (August 6, 2001):

  • Fixed bug where system suspend or other long delays would stop the GPS from updating.
  • Make AP name collection optional. Stop flooding LAN with WMP packets.
  • Handle misreported WEP on some IBSS networks.
  • Make card reconfiguration optional.
  • Windows Me support.

Version 0.3.21 (July 16, 2001):

  • Support for Dell Mini-PCI card.

Version 0.3.20 (July 13, 2001):

  • Added Beggarware license agreement.

Version 0.3.10 (July 12, 2001):

  • GPS code largely rewritten.
  • GPS on ports up to COM8 instead of COM4.
  • Adjustable scan speed.
  • Export summary files.

Version 0.3.00 (June 19, 2001):

  • Support for even more OEM cards (Now supported: Lucent, Dell 1150, Toshiba, Compaq, Enterasys/Cabletron, Elsa MC-11, ARtem Comcard, Buffalo Airstation WLI-PCM-L11)
  • Currently connected AP appears in a bold font in the tree view, and has an asterisk by its channel number in list view
  • This session's previously connected APs are marked with a '+' in list view
  • Added Ctrl+B key shortcut to toggle scanning
  • Filtering by channel number, ESSID, and capability flags
  • Saves entire data log as well as AP summary data
  • Graphical view of signal and noise over time if you select a single AP
  • Automatic reconfiguration of card, if desired. This will take your card out of peer mode, and unset the desired SSID if you have one. It also disassociates from networks that are out of range.
  • Creating a new document can be configured to automatically start scanning or not
  • Get the name of an AP, where supported (it won't be unless the AP doesn't have WEP, or you have the WEP key configured). It looks like Aironet APs don't support this.
  • Merge data files together
  • Ability to drag and drop column headers
  • Remembers view settings when switching views, and you can save the current settings as defaults
  • Read and write Pete Shipley's log format, as well as an extended version
  • Some APs respond to scan requests on multiple channels. These now appear as one item rather than multiple APs.
  • Uses NS1 file extension
  • Improved handling of invalid files
  • GPS should no longer lock up and stop responding
  • Removed non-functional toolbar buttons

Version 0.2.00 (May 16, 2001):

  • Works only with Lucent, Dell, and Toshiba cards
  • Doesn't crash the other PCMCIA devices that you have installed.
  • Should now work with USB devices.
  • Runs on Windows 2000, 95, 98 (and Me? - Untested).
  • Saves the data instead of making a 0 byte file.
  • Supports NMEA0183 GPS devices. It stores the location of the highest recorded SNR.
  • Lists the brand of AP hardware (based on the MAC address)
  • Shows current signal strength as well as the max, and has a dot that is colored to show the strength next to the AP name
  • Tree view to the left shows Channels, and Names; this will do more in a future version.
  • Makes a sound when it first sees an AP

Version 0.1.00 (May 5, 2001):

  • Initial proof of concept version, first public release.
  • Works only on Windows 2000.
  • Works with most Hermes chipset cards, but not if any other PCMCIA devices are installed.
  • Doesn't save data (creates a 0 byte file).


NetStumbler Usage and Configuration Examples

Index

User Scenarios

NetStumbler is designed to be useful to a number of different categories of users. A few of these categories are described below, along with some settings that might be useful.

Important Safety Note

Exposure to radio frequency radiation can be harmful. Read the manual that comes with your wireless equipment to see how far away you need to be from it in order to be safe. Use of an external antenna puts you at higher risk.

Wireless LAN Auditing

A corporate network administrator needs assurance that the wired LAN is not being exposed to unauthorized users. This can often happen when users set up their own wireless LANs for convenience. Such wireless LANs often have little or no security, which poses a risk to the entire LAN. The network administrator can use NetStumbler to detect the presence of these "rogue" wireless LANs.

  • Switch on Auto Reconfigure, to ensure that as many wireless LANs as possible are found.
  • If your LAN uses DHCP, make sure that DHCP is enabled on your wireless LAN card. You will then be able to tell if networks that you find are connected to your network.

Wireless LAN Coverage Verification

The owner of a wireless LAN can use NetStumbler to verify that an area is well covered by a good quality signal. NetStumbler can also be used to see how far the coverage area extends beyond its intended boundary.

  • Configure the wireless LAN card with the SSID and other settings of the LAN being verified.
  • Switch off Auto Reconfigure, so that only the desired SSID will be seen.

Site Survey

When installing or troubleshooting a wireless LAN, it is important to pick locations and channels in such a way that interference is minimized. A site survey typically includes finding out what existing items (microwave ovens, cordless phones, radio hams) are using the radio frequencies as the wireless LAN. A survey should done before installation of a new wireless LAN, and then subsequent surveys should be performed after installation. A full site survey requires special hardware such as an RF spectrum analyzer, but NetStumbler can also be used as part of a site survey.

  • Switch on Auto Reconfigure, to ensure that as many wireless LANs as possible are found.
  • Use a wireless card that reports noise levels. High noise levels are one of the indicators of interference.
  • A post-installation survey should include coverage verification, which may be performed with Auto Reconfigure turned off.
  • To avoid using networks that you observe and that you do not own, go to the Network Control Panel and unbind TCP/IP from your wireless LAN card.

Wardriving

Wardriving is the sport of detecting and/or locating wireless LANs. NetStumbler is a very popular tool for wardriving, because of its ease of use and GPS integration.

  • Switch on Auto Reconfigure, to ensure that as many wireless LANs as possible are found.
  • To avoid using the networks that you observe, go to the Network Control Panel and unbind TCP/IP from your wireless LAN card.
  • Use of a GPS receiver is highly recommended.

Antenna positioning

When setting up an antenna, NetStumbler can be used to assist with optimal antenna position and aim.

  • Connect the remote antenna to a wireless access point (or a wireless LAN card in IBSS mode)
  • Configure the wireless LAN card with the SSID and other settings of the remote system.
  • Switch off Auto Reconfigure, so that only the desired SSID will be seen.


User Interface

Menu Toolbar Status Bar Tree List

Click on an area of the image above for more detail on the feature, or choose from the list below:

  • Menu
  • Toolbar
  • Status Bar
  • Tree
  • List
  • Graph
  • Configuration Dialog
  • Context Menu


Configuration Dialog

The Configuration Dialog contains a number of tabs that let you configure various aspects of the operation of NetStumbler. Choose a tab to get more information about it:

  • General
  • GPS
  • Scripting
  • MIDI


General tab

Scan Speed controls how frequently NetStumbler sends probe requests. The time interval can be varied from 1.5 seconds (slow) to 0.5 seconds (fast).

Auto adjust using GPS allows the scan speed to be varied depending on the speed that is reported by the GPS receiver. If the GPS receiver is disconnected, not configured, or has no position/speed fix, this setting is ignored. Otherwise the scan speed varies in such a way that when you are at rest, the scan speed is twice as slow as normal. As you go faster, the scan speed increases, subject to some limits: On the faster settings, a scan never happens more frequently than 4 times per second; on the slower settings, a scan happens at least every 200 feet (61m).

The time interval (in seconds) between scans is shown below.

Scan interval (seconds)

Slow

- - -

- - -

- - -

Fast
Without GPS speed | 1.50 | 1.25 | 1.00 | 0.75 | 0.50
GPS, Stationary | 3.00 | 2.50 | 2.00 | 1.50 | 1.00
GPS, 25 mph / 40 km/h | 2.74 | 2.07 | 1.48 | 0.98 | 0.57
GPS, 50 mph / 80 km/h | 2.31 | 1.63 | 0.96 | 0.46 | 0.25
GPS, 75 mph / 120 km/h | 1.55 | 1.20 | 0.50 | 0.38 | 0.25
GPS, 100 mph / 160 km/h | 1.16 | 0.76 | 0.50 | 0.38 | 0.25

New document starts scanning does as it says: any time you create a new document, either by launching NetStumbler or by using the File » New menu item, scanning starts and the new document starts to receive the scan results. Any document that was previously receiving scan results will stop receiving them.

Reconfigure card automatically attempts to ensure that you can see as large a variety of SSIDs as possible, by attempting to keep your adapter in "Broadcast SSID" mode. Some access points do not respond to broadcast probes, so these access points will not appear unless you switch this setting off and configure the adapter to use that SSID.

Query APs for names attempts to gather names and IP addresses from access points that support such information. This information is gathered in various ways depending on your hardware configuration.

Save files automatically ensures that all modified files are saved every ten minutes, and saves them without asking for confirmation. This is particularly useful if you are often in a hurry to switch your machine off and do not want to be prompted to save your files.


GPS tab

The GPS tab allows you to configure your GPS receiver communication settings. NetStumbler requires that your GPS receiver use a serial protocol, which requires either a hardware serial port or a driver that emulates one. For example, if your GPS receiver uses Bluetooth, you can connect to it via a Bluetooth device that you configure to emulate a serial port on your PC.

Protocol allows you to choose the application protocol to use with your GPS receiver. It must match the settings used by the GPS receiver. Ths following protocols are supported:

  • NMEA 0183 (supported by most GPS receivers). The sentences recognized for position information are GPGGA, GPGLL, GPRMC. If your receiver outputs at least one of these then it will work with NetStumbler.
  • Earthmate, used by the (discontinued) serial Earthmate device, or any other device using the Rockwell "Zodiac" protocol. This uses 9600 baud, 8 data bits, no parity, 1 stop bit and no flow control, regardless of what settings you choose.
  • Garmin Binary, supported by devices manufactured by Garmin and which are configured to use protocol "GARMIN". This uses 9600 baud, 8 data bits, no parity, 1 stop bit and no flow control, regardless of what settings you choose.
  • Garmin Text, supported by devices manufactured by Garmin and which are configured to use protocol "Text Out".
  • Tripmate, a variant of NMEA 0183 used by the (discontinued) Tripmate device.

Port allows you to pick which communications port the GPS receiver is connected to. This can either be a real COM port or one that is emulated by a bluetooth device or a built-in GPS receiver. Choose Disabled if you are not using a GPS receiver.

The lower part of the dialog (Bits per second, Data bits, Parity, Stop bits, Flow control) determines the communication parameters for GPS data. These settings must match the settings used by your GPS receiver; check the manufacturer's documentation for details. The Earthmate and Garmin Binary protocols ignore all of these settings and use the values described above. Note that the NMEA 0183 standard requires 4800 baud, 8 data bits, no parity, 1 stop bit and no flow control, but your GPS receiver may support different settings.


MIDI tab

If you do not know what MIDI is, you can safely ignore this. Most importantly, leave Enable MIDI output of SNR in its default, unchecked, state.

If, however you are an experienced computer musician, you will be unimpressed to know that NetStumbler can generate a stream of usually unpleasant and discordant MIDI traffic for consumption by your MIDI devices. You also should leave Enable MIDI output of SNR unchecked unless you are participating in a cruel artistic experiment.

If you haven't a clue what this is for but want to try it anyway, here are some vague tips.

  • MIDI is used to interface with musical instruments. Your computer may have a built in MIDI driver that can play poor sounding musical instrument noises through your sound card. If you have a proper MIDI out port, you can use NetStumbler to scare your neighbors more than your garage band does usually.
  • Channel typically describes which channel to use. For General MIDI, channel 10 is for percussion.
  • Patch determines what kind of instrument is to be played on the channel. For General MIDI, for example, 4 is a honky-tonk piano, and 124 is a bird tweet.
  • Transpose shifts the notes by the number of semitones specified.


Scripting tab

Scripting allows you to extend NetStumbler in a variety of ways. For example, you could use it to ...

  • Interface with a mapping/GIS application
  • Send data to a database for custom processing
  • Drive a text-to-speech system, so you never have to look at the screen
  • Control custom robotic hardware (such as a device that locates access points, and attaches "I was here!" stickers to them, or fires lasers)
  • Other ideas that you may have

Type allows you to choose what sort of script should run:

  • No Scripting disables scripts and causes NetStumbler's default audio feedback mechanism to be used.
  • Default Script runs NetStumbler's built-in script that provides slightly more complex audio feedback.
  • External Script runs the script in the file of your choice. Use File and Browse to choose which one, and Language to determine which script engine to use.

Status reports what the script is doing, and in the case of an error in the script it will tell you a little more about it.

See also: Scripting Guide


Menu

Menu Items

This topic has not yet been written, and will be more complete in a future release.


Toolbar

This topic has not yet been written, and will be more complete in a future release.


Tree View

This topic has not yet been written, and will be more complete in a future release.


List View

The list view contains an item for each BSSID detected. A large amount of information is presented in the columns.

To customize the view, you can:

  • Drag the column heading boundaries to resize them.
  • Drag the column headings to change the order they appear.
  • Right click the column headings to hide and show them.
  • Use the View » Save Defaults menu item to save these changes.

The data in each column is described in the table below.

Column | Description
MAC | The text contains the BSSID for wireless devices. The icon shows the signal strength as reported in the last scan: Gray means the item was not detected, or a colored icon ranging from red to green reports the signal strength. A lock appears in the icon if encryption is enabled on the network. For devices on a wired network segment, the icon shows a T-shaped network cable and the MAC address is displayed.
SSID | The reported SSID. This may be blank for access points that report their existence but not their SSID. For wired network items, the SSID is assumed to be the SSID that was associated when the item was discovered.
Name | The device's name. This is reported rarely and only if "Query APs for names" is configured.
Chan | All the channels that the device has been seen on. The most recent one is listed first. Before the channel number may be a star (*), which means you are associated with the device, or a plus (+) which means that you were associated with it at some point.
Speed | The maximum reported bandwidth for the device (this is not the actual bandwidth). If you are using an 802.11b device, it may misreport the bandwidth of 802.11g networks as 11Mbps. Some devices are capable of 108Mbps but only report 54Mbps.
Vendor | The vendor assigned to the MAC, which may not be the actual equipment manufacturer.
Type | "AP" for a BSS, "Peer" for an IBSS.
Encryption | The word "WEP" will appear on an encrypted network, regardless of whether it is really using WEP.
SNR | The current Signal to Noise ratio, either in dB or arbitrary RSSI units.
Signal+ | The highest seen Signal value.
Noise- | The lowest seen Noise value.
SNR+ | The highest seen SNR value.
IP, Subnet | The IP configuration of the object, if available.
Latitude, Longitude, Distance | If you are using a GPS receiver, this indicates the estimated position of the object. This position is currently the location where the strongest signal was seen, which is never the actual location. Distance is measured from your current position to the object's estimated position.
First Seen | The time or date when the object was first discovered.
Last Seen | The most recent time or date when the object was seen.
Signal | The current Signal level, either in dB or arbitrary RSSI units.
Noise | The current Noise level, in dB. Not supported by all devices.
Flags | The 802.11 capability flags, in hexadecimal.
Beacon | The 802.11 beacon interval, in Kµs.


Graph View

The data that appears in the graph view is somewhat dependent on your hardware and device driver.

  • The green bars indicate signal strength. The higher the bar, the better the signal.
  • The red bars, if available, indicate noise level. The higher the bar, the higher the noise.
  • The gap between the green and red bars is equivalent to signal to noise ratio.
  • A purple bar indicates loss of signal, possibly temporary.

Some configurations, such as ORiNOCO and Prism cards, provide accurate measurements of both signal and noise data, which can be displayed in full with units of dBm.

Other configurations, and in particular any card using the NDIS 5.1 device access method, do not provide noise information, and may provide RSSI instead of signal information. In these cases, NetStumbler may omit the noise display and only display RSSI.

The graph view will automatically scroll to keep up with new data if you are viewing the rightmost part of it.


Tool Bar

Status Bar

This topic has not yet been written, and will be more complete in a future release.


Context Menu

When you right-click an item in the list view, a number of menu options appear. The items that appear vary depending on the item(s) selected.

In this example, the item Highlight on map has been added by a script. The script defines the text for the menu item and the action to be performed when it is selected.

If NetStumbler has determined the IP address or subnet of the selected item, the Look up (address) at (registry) items will appear. When clicked these will launch your web browser and perform a query on the registry that assigns IP addresses. The registry that you should use depends on your location:

  • ARIN assigns numbers for North America.
  • RIPE assigns numbers for Europe.
  • APNIC assigns numbers for the Asia/Pacific region.

Select All selects all the items in the list.

Delete Selected removes the selected item(s) from the list. This operation cannot be undone, so use it with caution.


Keyboard Shortcuts

The standard Windows shortcuts (Ctrl+O for Open, F1 for help, etc) are available.

Additionally you can use the Ctrl+B key combination to start and stop scanning.


Configuration Dialog

NetStumbler Scripting Guide

To use scripting in NetStumbler, you should be fluent in a scripting language that supports Active Scripting on the Windows platform. Examples of such languages are VBScript and JScript, which are available on most Windows platforms; others you might consider are PerlScript and Python, available from ActiveState.

Functions called by the application

OnEnableScan

Arguments

None.

Description

This is called when the user requests that scanning be started.

OnDisableScan

Arguments

None.

Description

This is called when the user requests that scanning be stopped.

OnScanComplete

Arguments

  1. FoundNew (Integer) - the number of networks that were discovered that did not already exist in the current scan document.
  2. SeenBefore (Integer) - the number of networks that were found but already exist in the current scan document.
  3. LostContact (Integer) - the number of networks that were found in the last scan, but did not respond in this one.
  4. BestSNR (Integer) - the highest detected signal-to-noise ratio, in units provided by the card. Usually this is in dB but some cards use their own arbitrary units.

Description

This is called when all of the results from the current scan have been processed.

OnScanResult

Arguments

  1. SSID (String) - the SSID (Network name)
  2. BSSID (String) - the BSSID (MAC address)
  3. CapFlags (Integer) - 802.11 capability flags
  4. Signal (Integer) - signal level, in units provided by the hardware. This may be dBm or arbitrary units of RSSI.
  5. Noise (Integer) - noise level, if the hardware reported it. Usually this is in dBm.
  6. LastSeen (Time) - When this BSSID was last seen

Description

This is called just after the application has received all scan results. It is called once for each item that was found. Since this is called frequently while scanning, the script should not perform complex operations that might take a long time to complete.

OnScanStart

Arguments

None.

Description

This is called just before the application initiates a scan.

OnGPSTimeout

Arguments

None.

Description

This is called when the GPS is not responding, most typically because it is unplugged or configured incorrectly. For most GPS protocols, this will be called once every few seconds.

OnGPSNoFix

Arguments

None.

Description

This is called when the GPS indicates that it is unable to provide a position fix. Usually this is caused by poor satellite visibility.

OnGPSPosition

Arguments

  1. Latitude (Double) - Current latitude in degrees. North is positive, South is negative.
  2. Longitude (Double) - Current longitude in degrees. East is positive, West is negative.
  3. Altitude (Double) - Current altitude above mean sea level in meters.

Description

This is called when the GPS indicates the current position.

OnGPSSpeed

This is called when the GPS indicates the current speed.

Arguments

  1. Speed (Double) - Current speed in knots.

OnIPChange

Called while scanning only when the IP address is reported to be changed. The IP address reported is the first one on the currently scanning adapter. NOTE: There are a number of cases where this function will get called but the IP address has not really changed - for example, the address changed on another adapter, or the IP routing or DNS information changed.

Arguments

  1. Addr (String) - New IP address, dotted format
  2. Mask (String) - New IP subnet mask, dotted format

OnPositionChange

Called to indicate that NetStumbler has changed its location information for a BSSID.

NOTE: A BSSID's location is currently determined to be the location where the strongest signal was seen, which is almost never the actual location. It is likely that a future version of NetStumbler will perform some postprocessing on results, which will make it possible for OnPositionChange to be called long after the BSSID was seen, unlike the current behavior.

Arguments

  1. SSID : String : SSID (Network name)
  2. BSSID : String : BSSID (MAC address)
  3. CapFlags : Integer : 802.11 capability flags
  4. MaxSNR: Integer : highest seen signal-to-noise ratio (dB) that had a position fix associated with it
  5. Lat : Double : Newly calculated latitude, degrees
  6. Lon : Double : Newly calculated longitude, degrees
  7. Alt : Double : Newly calculated altitude (currently not calculated)
  8. FixType : Integer : Reserved for future use

Functions provided by the application

In addition to the standard runtime provided by the scripting host, the application makes some additional functions available for use by scripts.

AddItemContextMenu

Arguments

  1. Callback (String) - Function to be called when menu item is selected
  2. MenuItem (String) - Text to appear on menu item

Description

Adds a custom item to the popup context menu for all networks. If the user selects this menu item, the named callback in the script is called with the BSSID and SSID of the network.

Example

Let us suppose you have custom VBScript that contains the following:

Sub LaserCallback (bssid, ssid)

  If Robot Is Nothing Then Set Robot = CreateObject("Skynet.T9000")

  Robot.PointLaserAt(bssid)

  Robot.Say "Hasta la vista, " & ssid

  Robot.FireLaser

End Sub

AddItemContextMenu "LaserCallback", "Fire Laser"

The last line of code registers the callback with NetStumbler. After this executes, every network's context menu will include an item labelled "Fire Laser". When selected, this menu item will cause the network's BSSID and SSID to be passed to "LaserCallback", which executes the custom code shown.

PlaySound

Arguments

  1. Sound (String)

Return Value

Boolean value indicating whether the operation succeeded. True indicates success, False indicates failure.

Description

Plays the requested sound file.

Internally, this calls the Win32 PlaySound API function with hModule = Null and fdwSound = SND_ASYNC | SND_NODEFAULT.

PlaySoundLoop

Arguments

  1. Sound (String)

Return Value

Boolean value indicating whether the operation succeeded. True indicates success, False indicates failure.

Description

Plays the requested sound file repeatedly. To stop playback, call the function again, passing an empty string.

Internally, this calls the Win32 PlaySound API function with hModule = Null and fdwSound = SND_ASYNC | SND_NODEFAULT | SND_LOOP.


User Interface

Index

Glossary

A

Ad Hoc Network

See IBSS.

B

BSSID

Basic Service Set, a wireless network that is formed by access points and clients.

BSSID

Basic Service Set IDentifier.

C

Capability Flags

The IEEE standards define a number of capability flags that describe the operation of a wireless LAN. The flags are described in the table below:

Flag |  | Meaning | Defined in
Decimal | Hexadecimal
1 | 1 | ESS | 802.11
2 | 2 | IBSS | 802.11
4 | 4 | CF Pollable | 802.11
8 | 8 | CF-Poll Request | 802.11
16 | 10 | Privacy (WEP) | 802.11
32 | 20 | Short Preamble | 802.11b
64 | 40 | PBCC | 802.11b
128 | 80 | Channel Agility | 802.11b
1024 | 400 | Short Slot Time | 802.11g
8192 | 2000 | DSSS-OFDM | 802.11g
256, 512, 2048, 4096, 16384, 32768 | 100, 200, 800, 1000, 4000, 8000 | Reserved for future use. | 802.11g

D

dB

dB is the abbreviation of decibel.

dBI

dBI is a decibel unit that measures antenna gain. 0 dBI is equivalent to an isotropic antenna, a theoretical antenna that radiates or receives equally in all directions. In reality no antenna is isotropic.

dBm

dBm is a decibel unit that measures power. 0 dBm is equivalent to 1 milliwatt. 30 dBm is equivalent to 1 watt.

decibel

A decibel is a logarithmic measure of something compared with a defined reference point. An increase of 10 dB corresponds to the value being multiplied by 10. A decrease of 10 dB corresponds to the value being divided by 10.

E

ESS

Extended Service Set. A wireless LAN configuration that uses access points to connect devices together. Typically the access points are connected together via a traditional wired LAN.

F

G

GPS

Global Positioning System, a collection of satellites in orbit around Earth that allows anyone with a suitable receiver to measure their location to within a few tens of feet of accuracy.

H

I

IBSS

An Independent Basic Service Set, also known as "ad hoc network" or "peer to peer network".

IEEE

The Institute of Electrical and Electronic Engineers, Inc.

J

K

L

LAN

Local Area Network. A collection of systems that are interconnected, typically via technology based on the IEEE 802 series of standards.

M

MiniStumbler

A version of NetStumbler for Windows CE devices. Not all of the features in NetStumbler are in MiniStumbler, but the files that they produce are interchangeable.

Monitor Mode

A mode of operation of a wireless NIC that allows it to receive all traffic on a given channel, regardless of the BSSID of the networks it sees. NetStumbler does not currently support Monitor Mode.

N

NIC

Network Interface Card.

NMEA

The National Maritime Electronics Association. NMEA defined the NMEA0183 protocol that is used by most GPSreceivers.

Noise level

The strength of interference or other unintended background signals that are being received. Usually measured in dBm.

O

P

Promiscuous Mode

A mode of operation of a NIC that allows it to receive all traffic on the network, regardless of the intended destination. In a wireless setting, this is all traffic with the currently associated BSSID.

Q

R

RSSI

Received Signal Strength Indication. A measurement of the strength (not necessarily quality) of the received signal, in arbitrary units. RSSI often appears on a scale from 0 to 100.

S

Signal to Noise Ratio

The ratio (signal strength / noise level) which measures signal quality. Usually measured in dB. Because decibels are logarithmic, the SNR in dB is the difference between Signal and Noise if they are both measured in the same dB units.

Signal strength

The strength of the signal being received. Usually measured in dBm.

SNR

See Signal to Noise Ratio.

SSID

Service Set IDentifier.

T

U

V

W

Wardriving

The sport of detecting and/or locating wireless LANs. The ethics (and, in most places, the laws) of wardriving dictate that the wireless LANs thus found must not be used without the owner's permission.

WEP

Wired Equivalent Privacy. A weak encryption scheme that is the standard on wireless networks. WEP has some well documented weaknesses that make it unsuitable for use with extremely sensitive data.

WPA

WiFi Protected Access. An encryption scheme that is stronger than WEP, but not as strong as AES.

X

Y

Z

Zoo

A place where animals can watch humans.


Compatibility Reporting

Sending a compatibility report helps make future versions of NetStumbler work better with the hardware that is most popular, and helps identify troublesome hardware for debugging. If your system configuration is not listed at http://www.stumbler.net/compat then please consider sending a compatibility report to help make the product better. No information is sent that can identify you.

What will be done with the information I send?

The information you send will be stored temporarily in secure storage on a web server.

What information is sent?

  • The beginning of the MAC address of the adapter, which identifies the manufacturer and model. The last 3 bytes, which might uniquely identify your card, are not sent.
  • The name of the device as it is known to Windows.
  • Information used internally by NetStumbler to determine how it discovered your hardware.
  • The version number of Windows that you are using.
  • The version number of the driver, firmware and hardware, if available.
  • The version of NetStumbler that you are running.
  • When you send the information, you will be taken to the web site and asked for more information such as how well the card is working for you.

Please visit http://www.stumbler.net/compat for more information.


License Agreement

NetStumbler® End User License Agreement

Marius Milner is willing to license this Software to you only if you accept all of the terms in this License Agreement. Please read the terms carefully before using the Software, because by installing or using this Software you are agreeing to be bound by the terms of this agreement. If you do not agree to these terms, Marius Milner will not license this Software to you, and you may not use the Software.

SOFTWARE LICENSE

Ownership of the Software. The enclosed software program (“Software”) and the accompanying written materials (“Documentation”) are owned by Marius Milner, or his suppliers, and are protected by United States copyright laws and by international treaties. The Software is licensed, not sold.

Marius Milner reserves all rights not expressly granted.

Grant of License. Marius Milner grants to you, as an individual, a revocable, nonexclusive, nontransferable license to install and use the Software on a computer or computers in your possession. If you are an entity, Marius Milner grants you the right to designate one individual within your organization to have the right to use the Software in the manner provided above.

Restrictions on Use and Transfer. You may not copy the Software or Documentation except solely for backup or archival purposes. You may not rent, lease, lend or provide commercial hosting services with the Software or otherwise transfer or assign the right to use the Software except as provided below. You may not reverse engineer, decompile, or disassemble the Software, except and only to the extent that such activity is expressly permitted by applicable law, notwithstanding this limitation. You may not create derivative works from the Software or the Documentation.

Termination. Marius Milner may terminate this Agreement if you fail to comply with its terms and conditions. In such event, you must destroy all copies of the Software in your possession.

General. Whenever possible, each provision of this License Agreement shall be interpreted in a manner as to be valid and effective under applicable law. If any provision is found to be unlawful, void or for any reason unenforceable, then that provision shall be deemed severable from this License Agreement and shall not affect the validity and enforceability of the remaining provisions. This Agreement is governed by the laws of the state of California. For questions concerning this Agreement, please contact Marius Milner via any means detailed in the “Contact Information” section.

Contact Information. For all contacts regarding this license agreement, please contact Marius Milner via electronic mail at mariusm@pacbell.net, or by fax at +1 (734) 376-6653.

LIMITED WARRANTY

Disclaimer. To the extent allowed by local law, the Software is provided to you “as is” without warranty of any kind, whether oral or written, express or implied. Marius Milner specifically disclaims any implied warranties or conditions of merchantability, satisfactory quality, non-infringement and fitness for a particular purpose. Some countries, states and provinces do not allow exclusions of implied warranties or conditions, so the above exclusion may not apply to you. You may have other rights that vary by country, state, or province.

Limitation of liability. Except to the extent prohibited by local law, in no event will Marius Milner or his affiliates or suppliers be liable for direct, special, incidental, consequential or other damages (including lost profit, lost data, or downtime costs), arising out of the use, inability to use, or the results of use of the Software, whether based in warranty, contract, tort or other legal theory, and whether or not advised of the possibility of such damages. Your use of the Software is entirely at your own risk. Should the Software prove defective, you assume the entire cost of all service, repair or correction. Some countries, states and provinces do not allow the exclusion or limitation of liability for incidental or consequential damages, so this limitation may not apply to you.

U.S. GOVERNMENT RESTRICTED RIGHTS

The Software and documentation are provided with Restricted Rights. Use, duplication, or disclosure by the Government is subject to restrictions at Defense Federal Acquisition Regulation Supplement, 252.227-7013, subparagraph (b)(3), or Federal Acquisition Regulation, 48 CFR 52.227-19, subparagraphs (c)(1) and (2), as applicable. Contractor/Manufacturer is Marius Milner, see “Contact Information” section for details.